<!DOCTYPE HTML>
<html lang="en">
<head>
<title>#Requires - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The #Requires directive displays an error and quits if a version requirement is not met." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>#Requires <span class="ver">[v1.1.33+]</span></h1>

<p>Displays an error and quits if a version requirement is not met.</p>

<pre class="Syntax"><span class="func">#Requires</span> Requirement</pre>

<h2>Parameters</h2>
<dl>
  <dt>Requirement</dt>
  <dd>
    <p>If this begins with the word "AutoHotkey" followed by a space or tab, it should be followed by a version string with optional leading "v". If <a href="../Variables.htm#AhkVersion">A_AhkVersion</a> is deemed compatible, loading of the script continues without displaying an error. For example, a script that requires v1.1.33 will also run on v1.1.33.01 and v1.1.34, but not v2.0.</p>
    <p>Otherwise, an error message is shown and the program exits.</p>
  </dd>
</dl>

<h2>Error Message</h2>
<p>If a different version of AutoHotkey is required, the message includes <a href="../Variables.htm#AhkVersion">A_AhkVersion</a>:</p>
<pre class="no-highlight">This script requires <i>%Requirement%</i>, but you have v<i>%A_AhkVersion%</i>.</pre>
<p>If the requirement was not recognized, the message format is as follows:</p>
<pre class="no-highlight">This script requires <i>%Requirement%</i>.</pre>
<p>If the script is launched with a version of AutoHotkey that does not support this directive, the error message is something like the following:</p>
<pre class="no-highlight">Line Text: #Requires <i>%Requirement%</i>
Error: This line does not contain a recognized action.</pre>

<h2>Remarks</h2>
<p>If the script uses syntax or functions which are unavailable in earlier versions, using this directive ensures that the error message shows the unmet requirement, rather than indicating an arbitrary syntax error. This cannot be done with something like <code>if (A_AhkVersion &lt;= "1.1.33")</code> because a syntax error elsewhere in the script would prevent it from executing.</p>
<p>When sharing a script or posting code online, using this directive allows anyone who finds the code to readily identify which version of AutoHotkey it was intended for.</p>
<p>Other programs or scripts can check for this directive for various purposes. For example, a launcher script might use it to determine which AutoHotkey executable to launch, while a script editor or related tools might use it to determine how to interpret or highlight the script file.</p>
<p>Version strings are compared as a series of dot-delimited components, optionally followed by a hyphen and pre-release identifier(s).</p>
<ul>
  <li>Numeric components are compared numerically. For example, v1.01 = v1.1, but a20 &gt; a112.</li>
  <li>Numeric components are always considered lower than non-numeric components in the same position.</li>
  <li>Any missing dot-delimited components are assumed to be zero. For example, v1.1.33-alpha is the same as v1.1.33.00-alpha.0.</li>
  <li>Non-numeric components are compared alphabetically, and are case sensitive.</li>
  <li>Pre-release versions are considered lower than standard releases. For example, a script that <code>#Requires AutoHotkey v2</code> will not run on v2.0-a112. To permit pre-release versions, include a hyphen suffix. For example: <code class="no-highlight">v2.0-</code>.</li>
  <li>Any suffix beginning with "+" is ignored.</li>
</ul>
<p>A trailing "+" is sufficient to indicate to the reader that later versions are acceptable, but is not required.</p>

<h2>Related</h2>
<p><a href="_ErrorStdOut.htm">#ErrorStdOut</a></p>

<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>#Requires AutoHotkey v1.1.33+
MsgBox This script will run only on v1.1.33.00 and later v1.1.* releases.</pre>
</div>

</body>
</html>
